 /*******************************************************************************
  * Copyright (c) 2003, 2005 IBM Corporation and others.
  * All rights reserved. This program and the accompanying materials
  * are made available under the terms of the Eclipse Public License v1.0
  * which accompanies this distribution, and is available at
  * http://www.eclipse.org/legal/epl-v10.html
  *
  * Contributors:
  * IBM Corporation - initial API and implementation
  *******************************************************************************/

 package org.eclipse.osgi.framework.adaptor;

 import java.io.File ;
 import java.io.IOException ;
 import java.net.URL ;
 import java.util.Dictionary ;
 import java.util.Enumeration ;
 import org.osgi.framework.*;
 import org.osgi.framework.Bundle;
 import org.osgi.framework.BundleException;

 /**
  * The <code>BundleData</code> represents a single bundle that is persistently
  * stored by a <code>FrameworkAdaptor</code>. A <code>BundleData</code> creates
  * the ClassLoader for a bundle, finds native libraries installed in the
  * FrameworkAdaptor for the bundle, creates data files for the bundle,
  * used to access bundle entries, manifest information, and getting and saving
  * metadata.
  * <p>
  * Clients may implement this interface.
  * </p>
  * @since 3.1
  */
 public interface BundleData {

     /** The BundleData is for a fragment bundle */
     public static final int TYPE_FRAGMENT = 0x00000001;
     /** The BundleData is for a framework extension bundle */
     public static final int TYPE_FRAMEWORK_EXTENSION = 0x00000002;
     /** The BundleData is for a bootclasspath extension bundle */
     public static final int TYPE_BOOTCLASSPATH_EXTENSION = 0x00000004;
     /** The BundleData is for a singleton bundle */
     public static final int TYPE_SINGLETON = 0x00000008;
     

     /**
      * Creates the ClassLoader for the BundleData. The ClassLoader created
      * must use the <code>ClassLoaderDelegate</code> to delegate class, resource
      * and library loading. The delegate is responsible for finding any resource
      * or classes imported by the bundle through an imported package or a required
      * bundle. <p>
      * The <code>ProtectionDomain</code> domain must be used by the Classloader when
      * defining a class.
      * @param delegate The <code>ClassLoaderDelegate</code> to delegate to.
      * @param domain The <code>BundleProtectionDomain</code> to use when defining a class.
      * @param bundleclasspath An array of bundle classpaths to use to create this
      * classloader. This is specified by the Bundle-ClassPath manifest entry.
      * @return The new ClassLoader for the BundleData.
      */
     public BundleClassLoader createClassLoader(ClassLoaderDelegate delegate, BundleProtectionDomain domain, String [] bundleclasspath);

     /**
      * Gets a <code>URL</code> to the bundle entry specified by path.
      * This method must not use the BundleClassLoader to find the
      * bundle entry since the ClassLoader will delegate to find the resource.
      * @see org.osgi.framework.Bundle#getEntry(String)
      * @param path The bundle entry path.
      * @return A URL used to access the entry or null if the entry
      * does not exist.
      */
     public URL getEntry(String path);

     /**
      * Gets all of the bundle entries that exist under the specified path.
      * For example: <p>
      * <code>getEntryPaths("/META-INF")</code> <p>
      * This will return all entries from the /META-INF directory of the bundle.
      * @see org.osgi.framework.Bundle#getEntryPaths(String path)
      * @param path The path to a directory in the bundle.
      * @return An Enumeration of the entry paths or null if the specified path
      * does not exist.
      */
     public Enumeration getEntryPaths(String path);

     /**
      * Returns the absolute path name of a native library. The BundleData
      * ClassLoader invokes this method to locate the native libraries that
      * belong to classes loaded from this BundleData. Returns
      * null if the library does not exist in this BundleData.
      * @param libname The name of the library to find the absolute path to.
      * @return The absolute path name of the native library or null if
      * the library does not exist.
      */
     public String findLibrary(String libname);

     /**
      * Installs the native code paths for this BundleData. Each
      * element of nativepaths must be installed for lookup when findLibrary
      * is called.
      * @param nativepaths The array of native code paths to install for
      * the bundle.
      * @throws BundleException If any error occurs during install.
      */
     public void installNativeCode(String [] nativepaths) throws BundleException;

     /**
      * Return the bundle data directory.
      * Attempt to create the directory if it does not exist.
      *
      * @see org.osgi.framework.BundleContext#getDataFile(String)
      * @return Bundle data directory or null if not supported.
      */

     public File getDataFile(String path);

     /**
      * Return the Dictionary of manifest headers for the BundleData.
      * @return Dictionary that contains the Manifest headers for the BundleData.
      * @throws BundleException if an error occurred while reading the
      * bundle manifest data.
      */
     public Dictionary getManifest() throws BundleException;

     /**
      * Get the BundleData bundle ID. This will be used as the bundle
      * ID by the framework.
      * @return The BundleData ID.
      */
     public long getBundleID();

     /**
      * Get the BundleData Location. This will be used as the bundle
      * location by the framework.
      * @return the BundleData location.
      */
     public String getLocation();

     /**
      * Get the last time this BundleData was modified.
      * @return the last time this BundleData was modified
      */
     public long getLastModified();

     /**
      * Close all resources for this BundleData
      * @throws IOException If an error occurs closing.
      */
     public void close() throws IOException ;

     /**
      * Open the BundleData. This method will reopen the BundleData if it has been
      * previously closed.
      * @throws IOException If an error occurs opening.
      */
     public void open() throws IOException ;

     /**
      * Sets the Bundle object for this BundleData.
      * @param bundle The Bundle Object for this BundleData.
      */
     public void setBundle(Bundle bundle);

     /**
      * Returns the start level metadata for this BundleData.
      * @return the start level metadata for this BundleData.
      */
     public int getStartLevel();

     /**
      * Returns the status metadata for this BundleData. A value of 1
      * indicates that this bundle is started persistently. A value of 0
      * indicates that this bundle is not started persistently.
      * @return the status metadata for this BundleData.
      */
     public int getStatus();

     /**
      * Sets the start level metatdata for this BundleData. Metadata must be
      * stored persistently when BundleData.save() is called.
      * @param value the start level metadata
      */
     public void setStartLevel(int value);

     /**
      * Sets the status metadata for this BundleData. Metadata must be
      * stored persistently when BundleData.save() is called.
      * @param value the status metadata.
      */
     public void setStatus(int value);

     /**
      * Persistently stores all the metadata for this BundleData
      * @throws IOException
      */
     public void save() throws IOException ;

     /**
      * Returns the Bundle-SymbolicName for this BundleData as specified in the bundle
      * manifest file.
      * @return the Bundle-SymbolicName for this BundleData.
      */
     public String getSymbolicName();

     /**
      * Returns the Bundle-Version for this BundleData as specified in the bundle
      * manifest file.
      * @return the Bundle-Version for this BundleData.
      */
     public Version getVersion();

     /**
      * Returns the type of bundle this BundleData is for.
      * @return returns the type of bundle this BundleData is for
      */
     public int getType();

     /**
      * Returns the Bundle-ClassPath for this BundleData as specified in
      * the bundle manifest file.
      * @return the classpath for this BundleData.
      */
     public String [] getClassPath() throws BundleException;

     /**
      * Returns the Bundle-Activator for this BundleData as specified in
      * the bundle manifest file.
      * @return the Bundle-Activator for this BundleData.
      */
     public String getActivator();

     /**
      * Returns the Bundle-RequiredExecutionEnvironment for this BundleData as
      * specified in the bundle manifest file.
      * @return the Bundle-RequiredExecutionEnvironment for this BundleData.
      */
     public String getExecutionEnvironment();

     /**
      * Returns the DynamicImport-Package for this BundleData as
      * specified in the bundle manifest file.
      * @return the DynamicImport-Packaget for this BundleData.
      */
     public String getDynamicImports();

     /**
      * Matches the distinguished name chains of a bundle's signers against a
      * pattern of a distinguished name chain.
      *
      * @param pattern the pattern of distinguished name (DN) chains to match
      * against the dnChain. Wildcards "*" can be used in three cases:
      * <ol>
      * <li>As a DN. In this case, the DN will consist of just the "*".
      * It will match zero or more DNs. For example, "cn=me,c=US;*;cn=you"
      * will match "cn=me,c=US";cn=you" and
      * "cn=me,c=US;cn=her,c=CA;cn=you".
      * <li>As a DN prefix. In this case, the DN must start with "*,".
      * The wild card will match zero or more RDNs at the start of a DN.
      * For example, "*,cn=me,c=US;cn=you" will match "cn=me,c=US";cn=you"
      * and "ou=my org unit,o=my org,cn=me,c=US;cn=you"</li>
      * <li>As a value. In this case the value of a name value pair in an
      * RDN will be a "*". The wildcard will match any value for the given
      * name. For example, "cn=*,c=US;cn=you" will match
      * "cn=me,c=US";cn=you" and "cn=her,c=US;cn=you", but it will not
      * match "ou=my org unit,c=US;cn=you". If the wildcard does not occur
      * by itself in the value, it will not be used as a wildcard. In
      * other words, "cn=m*,c=US;cn=you" represents the common name of
      * "m*" not any common name starting with "m".</li>
      * </ol>
      * @return true if a dnChain matches the pattern. A value of false is returned
      * if bundle signing is not supported.
      * @throws IllegalArgumentException
      */
     public boolean matchDNChain(String pattern);
 }

